로딩 중이에요... 🐣
13 백그라운드 실행 | ✅ 저자: 이유정(박사)
백그라운드 실행이란? 웹 서버 내부에서, 사용자의 요청을 처리한 후, 뒤에서 짧게 실행되는 추가 작업을 뜻해요.
예: 이메일 보내기
- 사용자가 회원가입을 하면, 바로 "회원가입 완료" 메시지를 응답으로 받고
- 그 뒤에 서버 안에서 이메일을 보내는 작업이 몰래 실행돼요.
- 사용자는 응답을 빨리 받고, 이메일은 뒤에서 발송됩니다.
요약: 요청–응답이 끝난 뒤, 서버 프로세스 안에서 돌아가는 추가 작업
실제 시나리오:
- 사용자는 어떤 웹사이트(예: 쿠팡, 인스타그램 등)에 회원가입을 해요.
- 가입 폼에 이메일 주소를 입력하고, “가입하기” 버튼을 누르면
- 다음과 같은 이메일이 날아옵니다:
📩 “
[OOO]님, 가입을 환영합니다!”
또는
📩 “이메일 인증을 완료해주세요” (링크 클릭 유도)
이게 왜 중요한가요? 이메일 인증 목적
- 진짜 이메일 주소인지 확인
- 로봇/스팸 회원 차단
- 나중에 비밀번호 찾기나 공지 발송 등을 위해 꼭 필요
개발자 입장에서 보면?
- 사용자가
/signupAPI에 회원가입 요청을 보냄 - 서버에서는:
- 사용자 정보 저장 (DB 저장)
- 응답: “가입 성공”
- 동시에 → 이메일을 보냄 ( 여기가 백그라운드 작업)
왜 백그라운드가 필요하냐면?
이메일 전송은 시간이 오래 걸릴 수 있어요
(외부 이메일 서버에 접속 → SMTP 프로토콜 → 보내기)
✔ 그래서 이 작업을 백그라운드에서 실행하면
→ 사용자에게는 빠르게 응답해주고
→ 이메일은 조용히 따로 발송되게 만들 수 있습니다.
FastAPI 서버와 사용자(클라이언트) 사이의 응답 흐름 사용자가 회원가입 버튼을 누르면:
[사용자(클라이언트)] → FastAPI 서버 → (응답 생성) → 사용자에게 즉시 응답
이 응답은 FastAPI가 직접 사용자에게 보내는 것입니다.
즉, JSON 응답이 "회원가입 완료" 같은 메시지로 사용자에게 바로 도착해요.
FastAPI 서버와 외부 이메일 서버 사이의 흐름
background_tasks.add_task(send_email, user_email)
이 코드는 이메일을 사용자에게 보내기 위한 작업을 예약하는 거예요.
그 실행 흐름은 다음과 같습니다:
[FastAPI 서버 내부 백그라운드 함수]
↓
이메일 서버(Gmail, Naver 등 SMTP)
↓
이메일 수신자(사용자 메일함)
이 과정은 응답을 다 보낸 다음에 실행돼요.
사용자는 이미 “회원가입 완료”라는 JSON 응답을 받고 화면을 보고 있을 때,
FastAPI는 뒤에서 이메일 전송을 시작합니다.
즉 쉽게 다시 정리하면 백그라운드 실행이란, 사용자가 요청을 보냈을 때 화면에는 빠르게 응답을 보여주고, 시간이 오래 걸리는 작업(예: 로그 기록, 이메일 전송 등)은 응답 이후에 조용히 처리함으로써 사용자에게 지연을 느끼지 않게 하는 기술입니다.
이메일 전송 같은 “느린 작업”이 백그라운드에서 제대로 실행되는지 확인하기 위한 실습 예제:
- 이메일 전송 = 실제로는 외부 서버에 연결해서 오래 걸리는 작업
- 이 예제에서는 → 그 역할을 log.txt 파일 쓰기로 흉내냄
- 백그라운드가 실행되는지 확인하려면
log.txt를 보면 됨
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def write_notification(email: str, message: str = ""):
"""
백그라운드에서 실행될 작업 함수.
이메일 주소와 메시지를 받아 로그 파일에 기록합니다.
"""
with open("log.txt", mode="w") as email_file:
content = f"notification for {email}:{message}\n"
email_file.write(content)
@app.post("/send-notification/{email}")
async def send_notification(
email: str,
background_tasks: BackgroundTasks
):
"""
이 엔드포인트에 요청이 들어오면,
write_notification 작업을 백그라운드로 실행하고
즉시 응답을 반환합니다.
"""
# 백그라운드 작업 등록
background_tasks.add_task(write_notification, email, message="some notification")
return {"message": "Notification sent in the background"}
from fastapi import FastAPI, BackgroundTasks
FastAPI: API 서버를 만들기 위한 핵심 클래스BackgroundTasks: 응답 이후에 실행할 작업을 등록할 수 있는 도우미 클래스
→add_task()메서드를 사용해서 작업 예약 가능
app = FastAPI()
- FastAPI 앱 인스턴스를 생성
- 이 객체가 웹 애플리케이션의 엔트리포인트가 됨 (
uvicorn으로 실행할 대상)
def write_notification(email: str, message: str = ""):
- 이 함수는 실제로 백그라운드에서 실행될 작업입니다.
- 매개변수:
email: 이메일 주소 문자열message: 전송할 메시지 (기본값은 빈 문자열)
"""
백그라운드에서 실행될 작업 함수.
이메일 주소와 메시지를 받아 로그 파일에 기록합니다.
"""
- 함수에 대한 docstring 주석
- 이 함수는 이메일을 실제로 보내는 대신, 파일에 내용을 저장하여 "전송한 것처럼" 동작하게 만듦
with open("log.txt", mode="w") as email_file:
"log.txt"라는 파일을 쓰기 모드("w")로 열기- 만약 파일이 이미 있으면 덮어씌움
- 새 파일이 없으면 생성됨
email_file은 파일 객체
content = f"notification for {email}: {message}\n"
- 이메일 주소와 메시지를 하나의 문자열로 결합
- 예시:
"notification for hello@example.com: some notification"
email_file.write(content)
- 위에서 만든 문자열을 파일에 실제로 기록
- 이 줄이 실행되면
"log.txt"에 내용이 들어가게 됨
@app.post("/send-notification/{email}")
/send-notification/{email}경로로 POST 요청이 들어왔을 때 실행될 핸들러를 정의- URL 경로의
{email}부분은 변수로 처리됨
async def send_notification(
email: str,
background_tasks: BackgroundTasks
):
- 요청이 들어왔을 때 실행되는 함수 (비동기 함수
async def) - 파라미터 설명:
email: URL 경로로부터 받아온 이메일 주소 (예:/send-notification/test@example.com)background_tasks: FastAPI가 자동으로 주입해주는 객체로, 백그라운드 작업을 등록할 때 사용
"""
이 엔드포인트에 요청이 들어오면,
write_notification 작업을 백그라운드로 실행하고
즉시 응답을 반환합니다.
"""
- 이 함수의 기능 설명을 위한 docstring
- 요청을 처리하고, 백그라운드 작업을 등록한 후 → 즉시 응답을 돌려주는 구조
background_tasks.add_task(write_notification, email, message="some notification")
- 백그라운드 작업을 등록하는 핵심 메서드
write_notification()함수를 호출하지 않고 예약만 합니다add_task()는 내부적으로 함수와 인자를 저장해 두고, 응답이 전송된 후 비동기적으로 실행합니다- 이 예시에서는:
write_notification("test@example.com", message="some notification")
이 호출이 예약됩니다.
return {"message": "Notification sent in the background"}
- 사용자에게 응답을 즉시 반환
- 이 응답이 전송되면 그 후에 예약된
write_notification()함수가 실행됨
Python 코드 실행기
